feat(types): ObjectKanbanSchema.objectName becomes a presence rule on both faces (bind | data | objectName) - #8412

Refs #7780

ObjectKanbanSchema.objectName becomes a presence rule on both published faces — at least one of bind, data, objectName — so the declared face matches the record-source ladder ObjectKanban actually walks.

Dispatched by the domain:spec @ objectui PM seat. Clause-②: yes (a published accept set widens), so needs:contract-review is hung on this PR and on the card. ⛔ This PR stays draft and unqueued awaiting that review — that is its sanctioned resting state, not a stall.

The two faces

packages/types/src/objectql.ts — objectName: string becomes objectName?: string, with a docblock naming the four rungs the renderer reads and why this is not the map/gantt/calendar ladder.

packages/types/src/zod/objectql.zod.ts — z.string() becomes z.string().optional(), and the member ends in .superRefine(requireKanbanRecordSource). That predicate is new and local, not requireRecordSource:

const KANBAN_RECORD_SOURCE_KEYS = ['bind', 'data', 'objectName'] as const;
function requireKanbanRecordSource(schema, ctx) {
  if (KANBAN_RECORD_SOURCE_KEYS.some((key) => schema[key] !== undefined)) return;
  ctx.addIssue({ code: 'custom', path: [], params: { code: 'RECORD_SOURCE_REQUIRED' },
    message: '`object-kanban` has no record source: declare one of `bind`, `data` or `objectName`' });
}

It is a function, not an export const, for the reason requireRecordSource gives right above it: the parity census reads ^export const out of that directory and would demand a registered TS counterpart.

Also in this PR, as the dispatch requires: the @ts-expect-error in object-calendar-record-source-7313.test.ts that asserted "objectName is still required on ObjectKanbanSchema" is deleted (leaving it would be TS2578 under tsconfig.test.json), and the literal it guarded is renamed and re-documented to record that the class boundary moved.

Accept set, before to after — from source, both entry paths

Measured with a probe against a rebuilt dist, at origin/main fff250ff and at this branch's HEAD deed7878. Every document carries groupBy, so objectName is the one member under test.

Negative controls — refused before, still refused after:

No row moved from ACCEPT to REFUSE. Two rows moved REFUSE to ACCEPT, and one refusal moved from a key-level failure to the named refinement at the root path.

One reading worth naming: with groupBy absent the refinement does not fire, because zod 4 skips refinements when the shape parse already failed. That is why the pin's "no record source" document carries groupBy — otherwise the case would go green for the lane key's reasons and stop saying anything about the record source.

groupBy requiredness (PR #7774) is not overturned

PR #7774's groupBy measurement explicitly excluded two readings from counting as a lane-less mode. Both are still refused, and the new pin asserts it:

• content/docs/utilities/data-objectstack.mdx — the dataSource json fragment. dataSource is not a rung of this ladder (ElementDataSourceGate maps its object onto objectName upstream of the node), so the fragment has no record source and no lane key and is refused for both.
• packages/plugin-list/src/ListView.tsx — the runtime-generated node, in the shape it emits when the view declared no lane field (groupBy: laneField with laneField undefined). Still refused at groupBy.

The retired groupField tombstone is likewise still refused by name.

objectui#7651 holds — and a reading on its radius

objectui#7651 ("Should ObjectKanban get a real record-source ladder?") was ruled B and closed not_planned on 2026-09-05; its epitaph is in the tree on KanbanSchema.data. It refuses a sixth getDataConfig producer, a ViewData retype of the board's data, and a staticData rung. Nothing here adds a rung, and the pin asserts that by IDENTITY rather than membership — shape.data === BaseSchema.shape.data and shape.bind === BaseSchema.shape.bind — because data and bind reach this member by inheritance through BaseSchema.extend, so membership alone cannot tell inherited from re-declared. A ViewData retype or a staticData addition replaces the entry and reddens it.

⚠️ On its literal radius, the dispatch asked me to measure rather than decide, so this is a reading handed back, not a decision. Measured: #7651's body is written entirely about KanbanSchema.data — the type: 'kanban' interface in packages/types/src/complex.ts — and its epitaph sits on that interface's data member. This card moves ObjectKanbanSchema (type: 'object-kanban', packages/types/src/objectql.ts), a different interface in a different file. So #7651 does not literally cover the member this PR edits. What it does cover, and what this PR obeys, is the substance: it refuses building a record-source ladder for the board, and no rung is built here — the only thing that moved is the requiredness of one member. The refusal list is respected on both interfaces regardless of which one it literally names. ⛔ I did not treat the literal gap as permission for anything; flagged for the contract reviewer.

In-repo census of authored object-kanban nodes

Instrument: every git-tracked file under apps/ · examples/ · content/ · packages/ whose bytes contain object-kanban (93 files), scanned for occurrences where the token is the value of a type key, then walked out to the enclosing brace-balanced literal and read at depth 1. 49 occurrences recognised.

Control — the instrument fires. A known-positive bind-only node was planted as a tracked file, the census re-run, and the plant reported by path and line (bind-only 1 to 2); removing it restored output byte-identical to the baseline run, with a clean git status. The positives above are the other half of that control: the walker finds the well-formed nodes too, not only the planted one.

Radius, stated rather than implied. It does not see nodes assembled at runtime by spread or variable, nodes whose type is a variable, or nodes assembled across files — and ⛔ authorship outside this repository is not measurable from this checkout at all: customer apps, published examples and stored page documents are simply not in the walk. No claim is made about them.

⚠️ Honest consequence, and it is not the flattering one. The single authored bind-only node in this repo — the BaseSchema.bind docblock example — also carries no groupBy, so this widening alone does not make it validate; it stays refused, at groupBy. The two data-only fixtures are the nodes this change actually unblocks: both carry an as never escape whose comment names this issue and says "when #7780 lands, this one follows". Those files are in packages/plugin-kanban/**, which this card does not hold, so they are not converted here.

Corrections to the inherited premises — both measured

① The plugin's own KanbanSchema at plugin-kanban/src/types.ts:89 does not exist — CONFIRMED false, as the dispatch stated. wc -l on that file is 59, so :89 cannot exist; grep -rnE '(interface|type|const) +KanbanSchema\b' packages/plugin-kanban/ returns 0 hits (exit 1) while the same pattern over packages/types/src/ fires on complex.ts and zod/complex.zod.ts (exit 0). The KanbanSchema in that file is a pure re-export, collapsed to one source by objectui#7664.

② The props type is a union — CONFIRMED, and this card needs no domain:ui leg. packages/plugin-kanban/src/ObjectKanban.tsx declares schema: KanbanSchema | ObjectKanbanSchema;, not the bare KanbanSchema that triage 5557326104 §4 measured. It already carries both arms, so there is nothing for a ui leg to change. Stronger than that: KanbanSchema.objectName was already optional, so on the union the property already resolved to string | undefined — making ObjectKanbanSchema.objectName optional does not move the union's property type at all. Measured, not inferred: pnpm exec vitest run --maxWorkers=2 packages/plugin-kanban/ is 30 files / 204 tests green on this branch, unchanged.

Parity — measured, not asserted

The dispatch declined to assert whether this widening moves a zod-mirror-parity.test.ts ledger row or an objectui#7279 header figure, and asked for a measurement. It does not, and here is the two-leg evidence rather than a claim:

• With the change: the parity suite and every objectui#7279 header pin are green in the 142-file packages/types/ run.
• With the change reverted (the ablation below): the parity suite is still green — it is not named among the failures. So its silence is not a side effect of anything this PR did.

The mechanism: no key is added or removed on either face, so both key sets are unchanged; optionality moved on both faces in the same stroke, so no required-vs-optional drift row is created; and zod 4 attaches .superRefine in place, leaving .shape exposed (measured directly, and the sibling members ObjectMapSchema / ObjectGanttSchema / ObjectCalendarSchema already carry refinements and sit in the same census). ⇒ zod-mirror-parity.test.ts needs no edit, and PR #8354 is not touched.

Reverse verification

Both faces reverted in one mutation, restored by git checkout HEAD -- (paths) under an EXIT INT TERM trap on absolute paths.

• Mutation reached disk, proven by blob hash, not by an exit code: objectql.ts 5d76024d to f7c01902; objectql.zod.ts 4ddc342c to 03b7ab9b. Anchored counts moved with it: superRefine(requireKanbanRecordSource) 1 to 0, the injected void requireKanbanRecordSource; 1, the optional objectName describe string 1 to 0, objectName?: string; 7 to 6.
• RED leg: 1 failed | 141 passed (142) files, 7 failed | 2705 passed (2712) tests. The one red file is object-kanban-record-source-7780.test.ts, and only it. All seven red assertions are this card's own subject (the four documents, the published entry point, .shape optionality, the no-rung identity pin, the sibling-ladder contrast). The groupBy-requiredness block and the off-disk renderer-read block stayed green, correctly — the mutation does not touch those facts.
• Restoration proven by state, not by exit code: both blob hashes equal their HEAD blobs exactly, git diff HEAD is 0 bytes, git status --porcelain empty.
• GREEN leg: 142 passed (142) files, 2712 passed (2712) tests.

No dist rebuild is needed between legs here, and that is a property of the resolution path rather than an assumption: the pin imports '../zod/objectql.zod', a relative source specifier inside the same package, so no dist/ is in the path — which the red leg demonstrates by going red with no rebuild at all.

Gates (exit codes captured before any pipe)

tsconfig.test.json demonstrably covers the new pin rather than excluding it: tsc -p tsconfig.test.json --listFiles puts it in a 605-file program (the 7313 pin is there as the control).

⚠️ One gate NOT MEASURED locally, declared rather than skipped silently: pnpm check:readme-exports exits 1 in this worktree, and 514 of its 517 findings are literally type entry ./dist/index.d.ts is not on disk -- run pnpm build first; the other three are ratchet floors that read the same unbuilt packages (packagesRead: found 2, floor is 25). It needs a full monorepo build, which CI does. It is unrelated to this diff on the evidence: no README is touched, no export is added or removed from any shipped entry point (the only renamed export const is inside a test file), and zero of its findings name @object-ui/types — the one package that is built here.

验收备注

Out-of-scope observations, recorded rather than filed and not acted on:

• Two fixtures in packages/plugin-kanban/** carry an as never escape whose comment says "when finding(types): ObjectKanbanSchema requires objectName on both faces while the renderer reads an undeclared inline data ahead of the fetch — the record-source ladder class (#7313) on a fourth view schema #7780 lands, this one follows" — ObjectKanban.overlayTitleI18n.test.tsx and ObjectKanban.overlayTitleNoProviderFallback.test.tsx. They can now become a real satisfies ObjectKanbanSchema. That package belongs to domain:ui's finding(types/plugin-kanban): an authored kanban document can PASS safeValidateSchema and still render empty — the validator and the renderer honour different faces #7664, so ⛔ not converted here. Follow-up for that seat.
• The BaseSchema.bind docblock teaches { "type": "object-kanban", "bind": "app.settings.users" } — a node that is still refused after this change, on the missing groupBy. Whether the teaching example should author a lane key is a docs judgement about a doc this card does not hold, and it is not a defect in either face.
• dataSource is authored on object-kanban nodes in content/docs/utilities/data-objectstack.mdx and is undeclared on ObjectKanbanSchema, riding BaseSchema's passthrough. It is not a rung of this ladder — ElementDataSourceGate maps its object onto objectName upstream — so it is deliberately out of the presence rule, and PR feat(types): declare ObjectKanbanSchema.groupBy and .limit, retire groupField on both faces (objectui#7322 item 1) #7774 already ruled that fragment out of the lane-less census. Noted only.

None of the three is a reproducible defect, a declared-contract violation, or a trap producing runtime-rejected metadata, so none was filed as a card.

⛔ Not flipped ready, not enqueued, no auto-merge, not self-approved. This session's GitHub identity is os-zhuang, which is both a GOVERNED_APPROVER and this PR's author.

Generated by Claude Code